<HTML>
<!-- (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2009 Hewlett-Packard Development Company, LP -->
<HEAD>
<TITLE>Jena Relational Database backend</TITLE>
<link href="../styles/doc.css" rel="stylesheet" type="text/css" />
</HEAD>
<BODY>



<h1>Jena2 Database Interface - How To Create Persistent Models</h1>



<p>The Jena2&nbsp; persistent storage subsystem implements an extension of the 
Model class that provides transparent persistence for models through the use of 
a database engine. Three database engines are currently supported, MySQL, 
Oracle, PostgreSQL and Microsoft SQL server, on both Linux and WindowsXP. </p>
<p>This document provides a brief overview of creating and accessing Jena2 
persistent models. Users are now encouraged to use the factory mechanisms described 
in <font size="2" face="Courier New"><a href="../how-to/model-factory.html">model-factory</a></font>. 
Previous mechanisms based on directly calling <code>ModelRDB</code> methods are 
now deprecated.</p>
<p>The various options for configuring and accessing persistent models are 
described in <font face="Courier New" size="2"> <a href="options.html">Options</a></font>.&nbsp; 
For details on installing and configuring the various database engines for use 
with Jena2, see the database engine-specific &quot;how to&quot; documents
(<a href="hsql-howto.html">HSQLDB Howto</a>,
<a href="mysql-howto.html">MySQL HowTo</a>,
<a href="derby-howto.html">Derby HowTo</a>,
<a href="postgresql-howto.html">PostgreSQL HowTo</a>,
<a href="oracle-howto.html">Oracle HowTo</a>,
<a href="mssql-howto.html">Microsoft SQL Server HowTo</a>).
</p>

<h2>Creating and Accessing Persistent Models</h2>

<p>In Jena2, all databases are multi-model and each model is, by default, stored 
in separate tables. Models may share database tables using the
<font face="Courier New" size="2"> 
<a href="options.html">StoreWithModel</a></font> option.  Currently, 
model names may be any string however users are encouraged to use URIs as model 
names for compatibility with planned future Jena features. Note that the model 
name &quot;DEFAULT&quot; is reserved for use by Jena (as the name of the default model) 
and attempts to create such a named model will cause an exception.</p>

<p>As mentioned above, there are two mechanisms for creating persistent models, 
one using factory methods and another using constructors for the ModelRDB class. 
However, the factory methods do not return a ModelRDB instance. Consequently, 
certain methods defined on ModelRDB are not available for factory-created 
models, e.g., remove, setDoDuplicateCheck. If an application needs these 
methods, the ModelRDB constructors should be used. This is an interim measure until the factory-created models 
support all the ModelRDB capabilities. Below we review creating and opening 
models for each mechanism.</p>

<h3>Factory Methods</h3>

<p>Creating or opening a model is a three-step process. First, the driver class 
must be loaded and a connection established to the database (note that in Jena2, 
the database type is specified as part of the database connection). Second, a model maker class is 
constructed. The model maker creates persistent instances of the Model class. 
Third, the model maker class is invoked to create new models or to open existing 
models. The following examples show how this is done.</p>

<font SIZE="2">
<blockquote>
  <pre><font face="Courier New">// database URL
String M_DB_URL         = <font SIZE="2" COLOR="#2a00ff">&quot;jdbc:mysql://localhost/test&quot;</font>;</font></pre>
  <pre><font face="Courier New">// User name</font></pre>
  <pre><font face="Courier New">String M_DB_USER        = <font SIZE="2" COLOR="#2a00ff">&quot;test&quot;</font>;</font></pre>
  <pre><font face="Courier New">// Password</font></pre>
  <pre><font face="Courier New">String M_DB_PASSWD      = <font SIZE="2" COLOR="#2a00ff">&quot;&quot;</font>;</font></pre>
  <pre><font face="Courier New">// Database engine name</font></pre>
  <pre><font face="Courier New">String M_DB = <font SIZE="2" COLOR="#2a00ff">&quot;MySQL&quot;</font>;</font></pre>
  <pre><font face="Courier New">// JDBC driver</font></pre>
  <pre><font face="Courier New">String M_DBDRIVER_CLASS = <font SIZE="2" COLOR="#2a00ff">&quot;com.mysql.jdbc.Driver&quot;</font>;</font></pre>
  <pre><font face="Courier New">// load the the driver class
Class.forName(M_DBDRIVER_CLASS);</font></pre>
  <pre><font face="Courier">
</font><font face="Courier New">// create a database connection
</font>IDBConnection <font face="Courier New">conn = </font></font><font SIZE="2" COLOR="#7f0055" face="Courier New"><b>new</b></font><font SIZE="2"><font face="Courier New"> DBConnection(M_DB_URL, M_DB_USER, M_DB_PASSWD, M_DB);</font></font></pre>
  <pre><font SIZE="2"><font face="Courier">
</font><font face="Courier New">// create a model maker with the given connection parameters
</font>ModelMaker <font face="Courier New">maker = ModelFactory.createModelRDBMaker(conn);</font></font></pre>
  <pre><font SIZE="2"></pre>
  <pre><font face="Courier New">// create a default model
Model defModel = maker.createDefaultModel();</font></pre>
  <pre><font face="Courier New">...</font></pre>
  <pre><font face="Courier New">// Open existing default model</font></pre>
  <pre><font face="Courier New">Model defModel = maker.openModel();</font></pre>
  <pre>&nbsp;</pre>
  <pre><font face="Courier New">// or create a named model
Model nmModel = maker.createModel(&quot;MyNamedModel&quot;);</font></pre>
  <pre><font face="Courier New">...</font></pre>
  <pre><font face="Courier New">// or open a previously created named model
Model prvModel = maker.openModel(&quot;AnExistingModel&quot;);</font></pre>
</blockquote>
</font>

<p>&nbsp;</p>

<h3><a name="ModelRDB Methods"></a>ModelRDB Methods</h3>
<p>If using datbase-specific, low-level options (see &quot;<a href="options.html">Options 
for Initialization and Access</a>&quot;), then the application may need to more 
directly use the ModelRDB interface.</p>
<p>
Database-backed RDF models are instances of the class <code>jena.db.ModelRDB</code> 
which supports the full <code>jena.model.Model</code> interface and also 
provides static methods to create, extend and reopen database instances.</p>

<p>ModelRDB supports several options (see &quot;<a href="options.html">Options for 
Initialization and Access</a>&quot;). Some
options alter the underlying database table structure and must be specified before the database is formatted.
These methods are invoked on the underlying database driver instance for the 
connection. Ideally, the driver class need not be exposed to Jena applications. 
Consequently, use of the driver class to set these options should be considered 
an interim measure until the option setting can be integrated into the factory 
methods. See <a href="#Enabling URI Compression">Enabling URI Compression</a> 
for an example of setting these options. Other options apply to models. See
<a href="#Disable Duplicate Checking">Disable Duplicate Checking</a> for an example 
of setting these types of options.</p>

<p>
Creating an instance of ModelRDB is a two-step process. As with the factory 
methods, the first step is to load the driver 
class and establish a database connection. Second, the static 
methods on ModelRDB are used to create new ModelRDB instances or to open 
existing ones. The following examples show how this is done.</p>

<font SIZE="2">
<blockquote>
  <pre><font face="Courier New">// As before ...</font></pre>
  <pre><font face="Courier New">String M_DB_URL          = <font SIZE="2" COLOR="#2a00ff">&quot;jdbc:mysql://localhost/test&quot;</font>;
String M_DB_USER         = <font SIZE="2" COLOR="#2a00ff">&quot;test&quot;</font>;
String M_DB_PASSWD       = <font SIZE="2" COLOR="#2a00ff">&quot;&quot;</font>;
String M_DB              = <font SIZE="2" COLOR="#2a00ff">&quot;MySQL&quot;</font>;
String M_DBDRIVER_CLASS  = <font SIZE="2" COLOR="#2a00ff">&quot;com.mysql.jdbc.Driver&quot;</font>;</font></pre>
  <pre><font face="Courier New">// load the the driver class
Class.forName(M_DBDRIVER_CLASS);</font></pre>
  <pre><font face="Courier">
</font><font face="Courier New">// create a database connection
</font>IDBConnection <font face="Courier New">conn = </font></font><font SIZE="2" COLOR="#7f0055" face="Courier New"><b>new</b></font><font SIZE="2"><font face="Courier New"> DBConnection(M_DB_URL, M_DB_USER, M_DB_PASSWD, M_DB);</font></font></pre>
  <pre>&nbsp;</pre>
  <pre><font face="Courier New">// ---- Directly use ModelRDB</font></pre>
  <pre>&nbsp;</pre><font SIZE="2">
  <pre><font face="Courier New">// create a default model
</font>ModelRDB <font face="Courier New">defModel = ModelRDB.createModel(conn);</font></pre>
  <pre><font face="Courier New">...
// Open an existing model.
</font>ModelRDB <font face="Courier New">defModel2 = ModelRDB.openModel(conn);</font></pre>
  <pre><font face="Courier New">...
</font></pre>
  <pre><font face="Courier New">// create a named model
</font>ModelRDB <font face="Courier New">nmModel = ModelRDB.createModel(conn,&quot;MyModelName&quot;);</font></pre>
  <pre><font face="Courier New">...</font></pre>
  <pre><font face="Courier New">// open a named model
</font>ModelRDB <font face="Courier New">nmModel2 = ModelRDB.openModel(conn,&quot;ExistingModelName&quot;);</font></pre>
  <pre><font face="Courier New">...</font></pre>
  <pre>&nbsp;</pre>
  </font>
</blockquote>
<code>
<pre></pre>
</code>
<h5><a name="Enabling URI Compression"></a>Enable URI prefix compression</h5>
<p>
As an example of setting a database configuration option, the following shows 
how URI prefix compression is enabled. By default, URIs are stored fully 
expanded in the statement tables. Also shown is doubling the size of the prefix 
cache.<blockquote>
<p>
<code>
<font face="Courier New" size="2">Class.forName(M_DBDRIVER_CLASS);<br>
DBConnection dbcon = new DBConnection(M_DB_URL, M_DB_USER, M_DB_PASSWD, M_DB);<br>
</font>
</code>

<font face="Courier New" size="2">dbcon.getDriver().setDoCompressURI(true);<br>
</font>
<code>
<font face="Courier New" size="2">ModelRDB model = ModelRDB.createModel(dbcon, "myModelName&quot;);<br>
// double the size of the prefix cache<br>
</font></code>

<font face="Courier New" size="2">int cacheSize = dbcon.getDriver().getCompressCacheSize();</font><code><font face="Courier New" size="2"><br>
</font></code>

<font face="Courier New" size="2">dbcon.getDriver().setCompressCacheSize(cacheSize*2);</font></blockquote>
<h5>Detect multiple models per database</h5>
<p>
In Jena2, all databases are multi-model and each model is, by default, stored in 
separate tables.  Here is an example that checks to see if a specific named model exists and then creates or reopens it as necessary:
<code>
<blockquote>
<pre><font face="Courier New" size="2">Class.forName(M_DBDRIVER_CLASS);
DBConnection dbcon = new DBConnection(M_DB_URL, M_DB_USER, M_DB_PASSWD, M_DB);
ModelRDB model;
if( !dbcon.containsModel(&quot;myModelName&quot;)
	model = ModelRDB.createModel(dbcon, &quot;myModelName&quot;);
else
	model = ModelRDB.open(dbcon, &quot;myModelName&quot;);</font>
</pre>
</blockquote>
</code>

<h5><a name="Sharing Tables"></a>Share tables among&nbsp; models</h5>

<p>In this example, a configuration option is used to specify that a new model 
should share the tables of an existing model. Unlike the previous option, this 
option can be set after the database is formatted. It affects only subsequently 
created models.</p>
<blockquote>

<p>
<code>
<font face="Courier New" size="2">Class.forName(M_DBDRIVER_CLASS);<br>
DBConnection dbcon = new DBConnection(M_DB_URL, M_DB_USER, M_DB_PASSWD, M_DB);<br>
ModelRDB model1, model2;<br>
model1 = ModelRDB.createModel(dbcon, "myModel1&quot;);&nbsp; // create a new model <br>
dbcon.getDriver().setStoreWithModel("myModel1&quot;);<br>
model2 = ModelRDB.createModel(dbcon, "myModel2&quot;); // model2 is stored with 
model1</font></code></p>
</blockquote>

<h5><a name="Disable Duplicate Checking"></a>Disable duplicate checking</h5>

<p>Some options apply to ModelRDB, e.g., query processing options. This example 
show how checking for duplicate statements can be disabled, as might be 
desirable when loading a large number of statements that the user is certain are 
duplicate-free.</p>
<blockquote>

<p>
<code>
<font face="Courier New" size="2">Class.forName(M_DBDRIVER_CLASS);<br>
DBConnection dbcon = new DBConnection(M_DB_URL, M_DB_USER, M_DB_PASSWD, M_DB);<br>
ModelRDB model = ModelRDB.createModel(dbcon, "myModelName&quot;);<br>
model.setDoDuplicateCheck(false);&nbsp; // disable duplicate checking</font></code></p>
</blockquote>
</BODY>
</HTML>